<!DOCTYPE HTML PUBLIC "-//ORA//DTD CD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>[Chapter 15] DatagramSocket</TITLE>
<META NAME="author" CONTENT="Mark Grand and Jonathan Knudsen">
<META NAME="date" CONTENT="Fri Aug  8 17:21:44 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java">
<META NAME="title" CONTENT="Java Fundamental Classes Reference">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java Fundamental Classes Reference" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch15_05.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 15<br>The java.net Package</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch15_07.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=refnamediv>
<H1>DatagramSocket</H1>

<H2>Name</H2>

DatagramSocket

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="ch15-REFSECT1-AUTOID.31">Synopsis</A></h2>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Class Name:<br>
<DD>

<P CLASS=para>
<tt CLASS=literal>java.net.DatagramSocket</tt>

<p>
<DT CLASS=varlistentry>Superclass:<br>
<DD>

<P CLASS=para>
<tt CLASS=literal>java.lang.Object</tt>

<p>
<DT CLASS=varlistentry>Immediate Subclasses:<br>
<DD>

<P CLASS=para>
<tt CLASS=literal>java.net.MulticastSocket</tt>

<p>
<DT CLASS=varlistentry>Interfaces Implemented:<br>
<DD>

<P CLASS=para>
None

<p>
<DT CLASS=varlistentry>Availability:<br>
<DD>

<P CLASS=para>
JDK 1.0 or later </DL>
</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="ch15-REFSECT1-AUTOID.32">Description</A></h2>

<P CLASS=para>
The <tt CLASS=literal>DatagramSocket</tt> class implements 
packet-oriented, connectionless data communication. In Internet parlance, 
this is the User Datagram Protocol, commonly known as UDP (see RFC 768). 
Each packet wanders through the network, routed by its destination address. 
Different packets can take different paths through the network and may 
arrive in a different order than they were sent. Furthermore, packets are 
not even guaranteed to reach their destination. It is up to an application 
that uses <tt CLASS=literal>DatagramSocket</tt> to 
determine if data is out of order or missing. While these features may 
seem like disadvantages of <tt CLASS=literal>DatagramSocket</tt>, 
there is also some advantage to using this class. 
Primarily, communication using <tt CLASS=literal>DatagramSocket</tt> 
is faster than <tt CLASS=literal>Socket</tt> stream 
communication because of the lack of overhead involved. 

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="ch15-REFSECT1-AUTOID.33">Class Summary</A></h2>

<DIV CLASS=screen>
<P>
<PRE>
public class java.net.DatagramSocket extends java.lang.Object {
  // Constructors
  public DatagramSocket();
  public DatagramSocket(int port);
  public DatagramSocket(int port, InetAddress laddr);     // New in 1.1
  // Instance Methods
  public void close();
  public InetAddress getLocalAddress();                   // New in 1.1
  public int getLocalPort();
  public synchronized int getSoTimeout();                 // New in 1.1
  public synchronized void receive(DatagramPacket p);
  public void send(DatagramPacket p);
  public synchronized void setSoTimeout(int timeout);     // New in 1.1
}
</PRE>
</DIV>

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="ch15-REFSECT1-AUTOID.34">Constructors</A></h2>

<DIV CLASS=refsect2>
<h3 CLASS=refsect2><A CLASS="TITLE" NAME="ch15-REFSECT2-AUTOID.14">DatagramSocket</A></h3>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.17">public DatagramSocket() throws SocketException</A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Throws<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>SocketException</tt><br>
<DD>

<P CLASS=para>
If any kind of socket error occurs.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>SecurityException</tt><br>
<DD>

<P CLASS=para>
If the application is not allowed to listen on the port. </DL>
<p>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This constructor creates a <tt CLASS=literal>DatagramSocket</tt> 
that is bound to any available port on the local host machine. </DL>
</DIV>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.18">public DatagramSocket(int port) throws SocketException</A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Parameters<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>port</tt><br>
<DD>

<P CLASS=para>
A port number. </DL>
<p>
<DT CLASS=varlistentry>Throws<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>SocketException</tt><br>
<DD>

<P CLASS=para>
If any kind of socket error occurs.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>SecurityException</tt><br>
<DD>

<P CLASS=para>
If the application is not allowed to listen on the given port. </DL>
<p>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This constructor creates a <tt CLASS=literal>DatagramSocket</tt> 
that is bound to the given port on the local host machine. </DL>
</DIV>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.19"><DIV CLASS=screen> <P> <PRE> public DatagramSocket(int port, InetAddress laddr) throws SocketException </PRE> </DIV></A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Availability<br>
<DD>

<P CLASS=para>
New as of JDK 1.1 

<p>
<DT CLASS=varlistentry>Parameters<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>port</tt><br>
<DD>

<P CLASS=para>
A port number.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>laddr</tt><br>
<DD>

<P CLASS=para>
A local address. </DL>
<p>
<DT CLASS=varlistentry>Throws<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>SocketException</tt><br>
<DD>

<P CLASS=para>
If any kind of socket error occurs.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>SecurityException</tt><br>
<DD>

<P CLASS=para>
If the application is not allowed to listen on the given port on the specified 
host. </DL>
<p>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This constructor creates a <tt CLASS=literal>DatagramSocket</tt> 
that is bound to the given port on the specified local host machine. </DL>
</DIV>

</DIV>

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="ch15-REFSECT1-AUTOID.35">Instance Methods</A></h2>

<DIV CLASS=refsect2>
<h3 CLASS=refsect2><A CLASS="TITLE" NAME="ch15-REFSECT2-AUTOID.15">close</A></h3>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.20">public void close()</A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This method closes the socket, releasing any 
system resources it holds. </DL>
</DIV>

</DIV>

<DIV CLASS=refsect2>
<h3 CLASS=refsect2><A CLASS="TITLE" NAME="ch15-REFSECT2-AUTOID.16">getLocalAddress</A></h3>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.21">public InetAddress getLocalAddress()</A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Availability<br>
<DD>

<P CLASS=para>
New as of JDK 1.1 

<p>
<DT CLASS=varlistentry>Returns<br>
<DD>

<P CLASS=para>
The local address of the socket. 

<p>
<DT CLASS=varlistentry>Throws<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>SecurityException</tt><br>
<DD>

<P CLASS=para>
If the application is not allowed to retrieve the address. </DL>
<p>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This method returns the local address to which this <tt CLASS=literal>DatagramSocket</tt> 
is bound. </DL>
</DIV>

</DIV>

<DIV CLASS=refsect2>
<h3 CLASS=refsect2><A CLASS="TITLE" NAME="ch15-REFSECT2-AUTOID.17">getLocalPort</A></h3>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.22">public int getLocalPort()</A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Returns<br>
<DD>

<P CLASS=para>
<tt CLASS=literal>The port</tt> number of the socket. 

<p>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This method returns the local port to which this <tt CLASS=literal>DatagramSocket</tt> 
is bound. </DL>
</DIV>

</DIV>

<DIV CLASS=refsect2>
<h3 CLASS=refsect2><A CLASS="TITLE" NAME="ch15-REFSECT2-AUTOID.18">getSoTimeout</A></h3>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.23">public synchronized int getSoTimeout() throws SocketException</A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Availability<br>
<DD>

<P CLASS=para>
New as of JDK 1.1 

<p>
<DT CLASS=varlistentry>Returns<br>
<DD>

<P CLASS=para>
The receive time-out value for the socket. 

<p>
<DT CLASS=varlistentry>Throws<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>SocketException</tt><br>
<DD>

<P CLASS=para>
If any kind of socket error occurs. </DL>
<p>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This method returns the receive time-out value for this socket. A value 
of zero indicates that the socket waits indefinitely for an incoming packet, 
while a non-zero value indicates the number of milliseconds it waits. </DL>
</DIV>

</DIV>

<DIV CLASS=refsect2>
<h3 CLASS=refsect2><A CLASS="TITLE" NAME="ch15-REFSECT2-AUTOID.19">receive</A></h3>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.24"><DIV CLASS=screen> <P> <PRE> public synchronized void receive(DatagramPacket p) throws IOException </PRE> </DIV></A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Parameters<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>p</tt><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>DatagramPacket</tt> that receives incoming data. </DL>
<p>
<DT CLASS=varlistentry>Throws<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>IOException</tt><br>
<DD>

<P CLASS=para>
If any kind of I/O error occurs.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>SecurityException</tt><br>
<DD>

<P CLASS=para>
If the application is not allowed to receive data from the packet's 
source.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>InterruptedIOException</tt><br>
<DD>

<P CLASS=para>
If a packet does not arrive before the time-out period expires. </DL>
<p>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This method receives a datagram packet on this socket. After this method 
returns, the given <tt CLASS=literal>DatagramPacket</tt> 
contains the packet's data and length, and the sender's address 
and port number. If the data that was sent is longer that the given packet's 
data buffer, the data is truncated.

<P CLASS=para>
If a time-out value is specified using the <tt CLASS=literal>setSoTimeout()</tt> 
method, the method either returns with the received packet or times out, 
throwing an <tt CLASS=literal>InterruptedIOException</tt>. 
If no time-out value is specified, the method blocks until it receives a 
packet. </DL>
</DIV>

</DIV>

<DIV CLASS=refsect2>
<h3 CLASS=refsect2><A CLASS="TITLE" NAME="ch15-REFSECT2-AUTOID.20">send</A></h3>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.25">public void send(DatagramPacket p) throws IOException</A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Parameters<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>p</tt><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>DatagramPacket</tt> to be sent. </DL>
<p>
<DT CLASS=varlistentry>Throws<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>IOException</tt><br>
<DD>

<P CLASS=para>
If any kind of I/O error occurs.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>SecurityException</tt><br>
<DD>

<P CLASS=para>
If the application is not allowed to send data to the packet's destination. </DL>
<p>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This method sends a packet from this socket. The packet data, packet length, 
destination address, and destination port number are specified by the given 
<tt CLASS=literal>DatagramPacket</tt>. </DL>
</DIV>

</DIV>

<DIV CLASS=refsect2>
<h3 CLASS=refsect2><A CLASS="TITLE" NAME="ch15-REFSECT2-AUTOID.21">setSoTimeout</A></h3>

<DIV CLASS=refsect3>
<h4 CLASS=refsect3><A CLASS="TITLE" NAME="ch15-REFSECT3-AUTOID.26"><DIV CLASS=screen> <P> <PRE> public synchronized void setSoTimeout(int timeout) throws SocketException </PRE> </DIV></A></h4>

<DL CLASS=variablelist>
<DT CLASS=varlistentry>Availability<br>
<DD>

<P CLASS=para>
New as of JDK 1.1 

<p>
<DT CLASS=varlistentry>Parameters<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>timeout</tt><br>
<DD>

<P CLASS=para>
The new time-out value, in milliseconds, for this socket. </DL>
<p>
<DT CLASS=varlistentry>Throws<br>
<DD>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>SocketException</tt><br>
<DD>

<P CLASS=para>
If any kind of socket error occurs. </DL>
<p>
<DT CLASS=varlistentry>Description<br>
<DD>

<P CLASS=para>
This method is used to set the time-out value that is used for <tt CLASS=literal>receive()</tt>. 
A non-zero value specifies the length of time, in milliseconds, that the 
<tt CLASS=literal>DatagramSocket</tt> should wait 
for an incoming packet. A value of zero indicates that the <tt CLASS=literal>DatagramSocket</tt> 
should wait indefinitely for an incoming packet. If a time-out value is 
needed, this method must be called before <tt CLASS=literal>receive()</tt>. </DL>
</DIV>

</DIV>

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="ch15-REFSECT1-AUTOID.36">Inherited Methods</A></h2>

<DIV CLASS=informaltable>
<P>
<TABLE CLASS=INFORMALTABLE>
<TR CLASS=row>
<TH ALIGN="LEFT">

<P CLASS=para>
Method</TH>
<TH ALIGN="LEFT">

<P CLASS=para>
Inherited From</TH>
<TH ALIGN="LEFT">

<P CLASS=para>
Method</TH>
<TH ALIGN="LEFT">

<P CLASS=para>
Inherited From</TH>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>clone()</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>equals(Object)</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>finalize()</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>getClass()</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>hashCode()</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>notify()</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>notifyAll()</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>toString()</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>wait()</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>wait(long)</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
</TR>
<TR CLASS=row>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>wait(long, int)</tt></TD>
<TD ALIGN="LEFT">

<P CLASS=para>
<tt CLASS=literal>Object</tt></TD>
<TD ALIGN="LEFT">&nbsp;</TD>
<TD ALIGN="LEFT">&nbsp;</TD>
</TR>
</TABLE>
<P>
</DIV>

</DIV>

<DIV CLASS=refsect1>
<h2 CLASS=refsect1><A CLASS="TITLE" NAME="ch15-REFSECT1-AUTOID.37">See Also</A></h2>

<P CLASS=para>
<tt CLASS=literal>DatagramPacket</tt>, 
<tt CLASS=literal>DatagramSocketImpl</tt>, 
<tt CLASS=literal>InetAddress</tt>, 
<tt CLASS=literal>InterruptedIOException</tt>, 
<tt CLASS=literal>IOException</tt>, 
<tt CLASS=literal>MulticastSocket</tt>, 
<tt CLASS=literal>SecurityException</tt>, 
<tt CLASS=literal>Socket</tt>, 
<tt CLASS=literal>SocketException</tt> 
</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch15_05.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch15_07.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>DatagramPacket</td>
<td width=171 align=center valign=top><a href="index/idx_0.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>DatagramSocketImpl</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
